使用 Zapier Platform CLI 添加即时触发器（REST Hooks）

REST Hooks 是轮询的替代方案。主要区别在于，它允许您的客户 Zap 即时触发；并且避免轮询触发器对您的 API 端点进行频繁（有时不必要的）请求，以检查新数据。

REST Hook 触发器在 Zap 编辑器中标记为 Instant。

在 Platform CLI 中构建时，请参考示例实现作为指导。

使用 REST Hook 触发器时，Zapier 会通过每个已激活 Zap 的唯一 URL 订阅您的服务器，而您的应用会在触发事件发生时，向该唯一 URL 发送数据负载，从而触发特定 Zap。

REST Hooks 与静态 Webhooks 不同。在静态 Webhooks 中，您的客户需要手动复制并粘贴每个 Zap 的特定 URL，以连接您的应用和他们的 Zap；而在 REST Hooks 中，此过程会由 Zapier 和您的应用自动处理。

Zapier 不支持 Webhook 订阅的身份确认。

先决条件

您的应用支持 REST Hooks——即可以通过 REST API 操作的 Webhook 订阅。
一种存储我们发送给您的唯一 URL 的方式，例如数据库。
一种在特定事件发生时，以 JSON 格式向每个存储的 URL 发送数据负载的方式，从而触发相关的 Zap。
一个或多个端点，用于接收订阅和退订数据负载（这些可以是相同的端点或单独的端点）。
如果您的 Webhook 订阅有到期时间，请确保订阅端点在响应中包含一个 expiration_date 属性，该属性为 ISO8601 格式的日期。平台会在到期日期后自动尝试重新订阅。

当 Zap 被启用时，subscribeHook 函数会携带包含触发 Zap 的唯一 URL 的数据负载被调用。将此 URL 存储起来，并将其与一个 ID 关联起来，以便在您想要触发此 Zap 时使用。在响应中返回该 ID，以便 Zapier 在后续的退订中使用。

当 Zap 被禁用时，unsubscribeHook 函数会被调用，以通知您的应用删除先前为此 Zap 存储的唯一 URL。

1. 编写 `subscribeHook` 函数

首先要实现的函数是 subscribeHook 函数，它提供用于触发 Zap 的 URL。需包含以下参数：

url 应为 bundle.targetUrl，这是 Zapier 为每个已激活 Zap 自动生成的 URL。
任何您想要从 inputFields 发送的其他数据。

const subscribeHook = (z, bundle) => {
  const data = {
    url: bundle.targetUrl,
    field: bundle.inputData.field,
    // etc
  };

  const options = {
    url: 'subscription endpoint url',
    method: 'POST',
    body: data
  };

  // make the request and parse the response - this does not include any error handling.
  return z.request(options).then((response) => response.data);
}

此函数会在触发器的 performSubscribe 方法中被调用：

module.exports = {
  // Other data about the Trigger, e.g. key, name, etc. omitted
  performSubscribe: subscribeHook
};

此函数会在每次启用 Zap 时运行。

2. 编写 `unsubscribeHook` 函数

接下来要实现的函数是 unsubscribeHook 函数，它会在 Zap 被禁用时被调用。这会通知您的服务器删除您先前存储的 URL，并停止向其发送数据负载。如果您的 API 在 Zap 退订后继续向该 URL 发送通知数据负载，Zapier 会返回 410 响应。

bundle.subscribeData.id 是必需的——这是相关钩子的 ID。您可以将它分配给一个 hookID 变量或类似变量。

需包含以下参数：

const unsubscribeHook = (z, bundle) => {
  // bundle.subscribeData contains the parsed response JSON from the subscribe request.
  const hookId = bundle.subscribeData.id
  const options = {
    url: `unsubscription endpoint url/${hookId}`,
    method: 'DELETE'
  }
  return z.request(options).then((response) => response.data);
};

此函数会在触发器的 performUnsubscribe 方法中被调用：

module.exports = {
  // Other data about the Trigger, e.g. key, name, etc. omitted
  performUnsubscribe: unsubscribeHook
};

如果 REST Hook 触发器缺少订阅或退订函数，它会对用户显示为静态 Webhook。静态钩子在公共集成中不受支持，但如果集成打算保持私有状态，可以使用它们。

3. 编写 `perform` 函数

接下来要实现的函数是 perform 函数，它会在您的应用每次向 Zapier 交付通知数据负载时被调用。这就是实际触发 Zap 的函数。通常，您只需返回清理后的请求作为一个数组。请求返回的数据必须是一个数组。

const parseHookPayload = (z, bundle) => {
  // bundle.cleanedRequest will include the parsed JSON object (if it's not a
  // test poll) and also a .querystring property with the URL's query string.
  const payload = {
    id: bundle.cleanedRequest.id,
    name: bundle.cleanedRequest.name,
    directions: bundle.cleanedRequest.directions,
    style: bundle.cleanedRequest.style,
    authorId: bundle.cleanedRequest.authorId,
    createdAt: bundle.cleanedRequest.createdAt
  };

  return [payload];
};

接着是：

module.exports = {
  // Other data about the Trigger, e.g. key, name, etc. omitted
  perform: parseHookPayload
};

4. 编写 `performList` 函数

要实现的最后一个函数是 performList 函数，用于在 Zap 编辑器中测试触发器时收集样本数据。虽然这是可选的，但不定义 performList 会导致用户体验不佳，并且对于公共应用是必需的。

最常见的情况是，向您的 API 的某个端点发送 GET 请求，该端点会从用户帐户返回响应，并使用与 Webhook 交付数据时完全相同的模式返回数据。

返回的响应数据必须是一个数组，即使数组中只包含一个对象。它必须与 Webhook 交付数据时使用的模式完全相同，否则，在后续 Zap 步骤中从此样本映射的字段会在实际运行时出错。

const getFallbackSample = (z, bundle) => {
  // For the test poll, you should get some real data, to aid the setup process.
  const options = {
    url: 'sample endpoint here',
    method: 'GET',
    params: {
      style: bundle.inputData.style
    }
  };

  return z.request(options).then((response) => response.data);
};

module.exports = {
  // Other data about the Trigger, e.g. key, name, etc. omitted
  performList: getFallbackSample
};

5. 测试您的 API 请求

要测试 REST Hook 触发器，请在编辑器中构建一个 Zap。

6. 定义样本数据和 outputFields

按照指南定义样本数据和输出字段。您可以在这里查看示例。

BasicHookOperationSchema

`subscribeHook`

这是一个函数，用于向您控制的端点发送数据负载。您需要获取 targetUrl 参数并安全存储它，因为此 URL 用于在触发事件发生时从您的应用向 Zapier 发送数据，从而触发 Zap。您可以在这里查看示例。

`unsubscribeHook`

这是一个函数，用于向您控制的端点发送数据负载，包括 targetUrl 参数。您需要完全停用或从存储中删除该 URL，因为与该 URL 关联的 Zap 不再会触发请求。如果您的 API 在 Zap 退订后继续向该 URL 发送通知数据负载，Zapier 会返回 410 响应。您可以在这里查看示例。

`perform`

这是一个处理传入 Webhook 请求的函数。不需要在此处进行任何 HTTP 请求。如示例应用中所示这里，这可以简单地从 bundle.cleanedRequest 中获取数据并构建一个新对象，然后在数组中返回它。重要的是，要按照这里指定的方式在数组中返回此对象。

`performList`

在 Zap 编辑器中测试 REST Hook 触发器时，只会调用 performList，而不会调用 perform。performList 理想情况下应向一个端点发送 HTTP 请求，以返回样本数据，这些数据可映射到用户 Zap 的后续步骤。您可以在这里查看示例。这对于公共应用是必需的，对于私有应用强烈推荐，以避免用户在设置 Zap 时感到困惑。

先决条件​

1. 编写 subscribeHook 函数​

2. 编写 unsubscribeHook 函数​

3. 编写 perform 函数​

4. 编写 performList 函数​

5. 测试您的 API 请求​

6. 定义样本数据和 outputFields​

BasicHookOperationSchema​

subscribeHook​

unsubscribeHook​

perform​

performList​